What is an R script

R script is a simple text file (with extension .R, for example my_script.R) containing commands written in R language.
When an R script is sourced, the lines of the script are one-by-one copied to the Console and immediately executed.
An R script allows to save R commands (without saving, the commands given in the Console are executed and forgotten).

⚠️In this course R scripts are not discussed.

What is an R Markdown document

An R Markdown document (with extension .Rmd, for example my_report.Rmd) is an extension of an R script.
It is a format for developing elegant and reproducible reports.
It is a simple text file consisting of:

  • Chunks written in R language, where data analysis is performed.
  • Free text written in Markdown notation, possibly containing: sections, lists, tables, hyperlinks, formulae: \(r=\sqrt{x^2+y^2}\), etc.

The Knit operation converts an R Markdown document into a report file.
Many report output formats are available: HTML, PDF (printable pages or presentations), Microsoft Word documents, etc.
(For example: this page is written in R Markdown and knitted to HTML)

🎥 Watch R Markdown introduction video from RStudio.

➡️Go to Markdown tutorial to quickly practice writing text with Markdown notation.

Create a new R Markdown document

⚠️Before creating a new document, first check whether you work in the Learning_R project.

From the RStudio menu choose: File↣New File↣R Markdown....
In the dialog box you may specify some details of the analysis (later change is possible):

  • Title of the analysis.
    (Note, this is NOT the name of the .Rmd file; this name will be given when the document gets saved.)
  • Name of the author.
  • Output format (for now, select HTML).

Once accepted, a new document Untitled1 is shown.
The document is not empty; it contains an example written in R Markdown.

Knit an R Markdown document

Knitting is the name of the process of conversion from R Markdown text file to a report in one of the target formats (for example: HTML).

  • Press the Knit button to start the conversion.
  • If the R Markdown document does not have a name yet, a save dialog box will pop up to ask for the file name.
  • Some libraries might get automatically installed before the first Knit.
  • The knitting process might take a few seconds and then the final document should appear either in a new window or in the Viewer pane.
    The Figure below shows the result of knitting of the standard example (R Markdown was saved as Lesson_1.Rmd and was knitted to HTML file Lesson_1.html):

Parts of an R Markdown document

An R Markdown document consists of: header, chunks and free text.

The header:

  • Is located at the first lines of the file.
  • Starts and ends with a line containing --- (three minus symbols).
  • May specify title, author, date and possibly other properties of the document.

🏃Locate the header in the Figures above and below.

🏃Create a new R Markdown document and make it empty (remove the example text). Then write a header at the top based on the Figure below. Add your name as the author and change the title. Knit to see the effect.

🏃Check the Files panel. Find there the HTML file which was created by knitting.

A chunk:

  • Is a place where code in R language is written. The result of this code will be displayed below the chunk.
  • Starts with a line containing ```{r} (three backticks, then r in curly braces).
  • Ends with a line containing ```
  • Has gray background by default in RStudio.

🏃Locate two chunks in the Figure below. Locate a chunk (with a more complex R code) in the Figure above.

🏃Type a new chunk in your document, based on the Figure below. Put a simple R expression into the chunk. Knit to see the effect.

🏃In your document add a new chunk with another R expression. Press the green play button in the upper right corner of the chunk area. Change the expression. Press play again.

A free text:

  • Not the header and not a chunk.
  • Has white background by default in RStudio.

🏃Locate two free text regions in the Figure below.

🏃In your document add some free text. Try to add a section and possibly subsections. Knit to see the effects.

Editing an R Markdown document

Important difference:

  • When you run a chunk it may use the variables currently present in memory (see Environment).
    This is good when you develop your report.
  • Knit button processes the whole R Markdown with no variables in memory (empty Environment).
    This is necessary for the final version of your report.

Useful hints:

  • To insert a new chunk you may use menu Code↣Insert Chunk or the keyboard shortcut shown in the menu.
  • To run the chunk with the cursor you may use Code↣Run Region↣Run Current Chunk or the keyboard shortcut shown in the menu.
  • To run the line with the cursor or selected text you may use Ctrl-Enter key combination.

First R Markdown report for pulse table

In the next parts of the course we will discuss how to build a report for a table loaded from a file pulse.csv.
We will open a new report file Lesson_2.Rmd and load the table. Then we show the table. In case of troubles consult the images provided below.

How to create

🏃Follow the steps from the sections above to create a new R Markdown document Lesson_2.Rmd. Be sure to work in the project Learning_R (where you copied the table file).

🏃In the R Markdown document: fill the header of the file with correct author/date and remove all demo chunks.

In this course we extend R with functionality provided by the tidyverse package.
It might be needed once to install this package using menu Tools↣Install Packages...: type tidyverse in Packages field and press Install.

Usually there are many packages installed, but you need only a few of them.
The following command loads the library – allows to use the package tidyverse:

library( tidyverse )

🏃In your R Markdown document create the first chunk with this command. Run the chunk (some messages will be shown).

Next, the function read_csv reads the table from the file provided in the argument.
We assign the result (which is the loaded table) to the variable pulse:

pulse <- read_csv( "pulse.csv" )

🏃Type this command in a second chunk. No error should be shown when you run this chunk. Also no result because it gets assigned to the variable.

Finally, when you print the variable, it should show you a few lines of the table.

pulse

🏃Add the above line at the end of the second chunk. Run the chunk.

🏃Finally knit the complete document. There should be no errors and a report should be shown.

R Markdown document

After running chunks


Copyright © 2021 Biomedical Data Sciences (BDS) | LUMC